﻿
''' <summary>
''' Manages the display of application tips.
''' </summary>
''' <remarks></remarks>
<CLSCompliant(True)> _
Public Class TipManager
    Implements IDisposable

#Region " Fields "

    Private _XmlTipFileName As String
    Private _Data As TipsDataSet
    Private _ShowTipsAtStartup As Boolean = True
    Private _DisplayMethod As TipDisplayMethod = TipDisplayMethod.Normal

    Private _DisposedValue As Boolean = False        ' To detect redundant calls (IDisposable support)

#End Region

#Region " Constructors "

    ''' <summary>
    ''' Creates a new TipManager instance based on the tip data XML found at the given tip file name.
    ''' </summary>
    ''' <param name="tipFileName">String - the filename and path of the XML tip file containing the tips to display.</param>
    ''' <remarks></remarks>
    Public Sub New(ByVal tipFileName As String)

        XmlTipFileName = tipFileName
        _Data = New TipsDataSet(tipFileName)

    End Sub

    ''' <summary>
    ''' Creates a new TipManager instance based on the tip data XML found at the given tip file name.
    ''' </summary>
    ''' <param name="tipFileName">String - the filename and path of the XML tip file containing the tips to display.</param>
    ''' <param name="displayMethod">TipDisplayMethod - specifies how the first tip will be shown.</param>
    ''' <remarks></remarks>
    Public Sub New(ByVal tipFileName As String, ByVal displayMethod As TipDisplayMethod)

        MyClass.New(tipFileName)
        _DisplayMethod = displayMethod

    End Sub

#End Region

#Region " Properties "

    ''' <summary>
    ''' Gets or sets the XML tip file to be used by this instance.
    ''' </summary>
    ''' <remarks>The tip file must exist on the file system.</remarks>
    Public Property XmlTipFileName() As String
        Get
            Return _XmlTipFileName
        End Get
        Set(ByVal value As String)

            If String.IsNullOrEmpty(value) Then _
                Throw New ArgumentNullException("value")

            If Not My.Computer.FileSystem.FileExists(value) Then _
                Throw New ArgumentException(String.Format("{0} does not exist on the file system.", value))

            _XmlTipFileName = value

        End Set
    End Property

    ''' <summary>
    ''' Gets the instance of the TipsDataSet used by this manager to display application tips.
    ''' </summary>
    Public ReadOnly Property TipsData() As TipsDataSet
        Get
            Return _Data
        End Get
    End Property

    ''' <summary>
    ''' Gets or sets a value indicating if the user wishes for tips to show at startup.
    ''' </summary>
    ''' <remarks>This will only hold a user specified value after the 
    ''' <seealso cref="ShowApplicationTip">ShowApplicationTip()</seealso>
    ''' method has been called.<br />
    ''' </remarks>
    Public Property ShowTipsAtStartup() As Boolean
        Get
            Return _ShowTipsAtStartup
        End Get
        Set(ByVal value As Boolean)
            _ShowTipsAtStartup = value
        End Set
    End Property

    ''' <summary>
    ''' Gets or sets a TipDisplayMethod used to specify which tip to display when the form loads.
    ''' </summary>
    Public Property DisplayMethod() As TipDisplayMethod
        Get
            Return _DisplayMethod
        End Get
        Set(ByVal value As TipDisplayMethod)
            _DisplayMethod = value
        End Set
    End Property

#End Region

#Region " Methods "

    ''' <summary>
    ''' Presents the user with the next application tip.
    ''' </summary>
    ''' <remarks></remarks>
    Public Sub ShowApplicationTip()

        Using form As New Forms.TipsForm(_Data, _DisplayMethod)

            form.ShowTipsAtStartup = _ShowTipsAtStartup

            If form.ShowDialog() = Windows.Forms.DialogResult.OK Then
                'If all tips have been displayed, reset the displayed dates.  This will allow for tips to show again.
                If _Data.Tips.AllTipsDisplayed() Then
                    _Data.Tips.ResetLastDisplayedDates()
                End If
                _ShowTipsAtStartup = form.ShowTipsAtStartup
                _Data.SaveToDisc(_XmlTipFileName)
            End If

        End Using
    End Sub

#Region " IDisposable Support "

    ''' <summary>
    ''' Frees resources used by this instance.
    ''' </summary>
    ''' <param name="disposing">Boolean - used to properly implement IDisplosable pattern.</param>
    ''' <remarks></remarks>
    Protected Overridable Sub Dispose(ByVal disposing As Boolean)
        If Not Me._DisposedValue Then
            If disposing Then
                _Data = Nothing
            End If

            _XmlTipFileName = String.Empty
        End If
        Me._DisposedValue = True
    End Sub

    ''' <summary>
    ''' Frees resources used by this instance.
    ''' </summary>
    ''' <remarks></remarks>
    Public Sub Dispose() Implements IDisposable.Dispose
        ' Do not change this code.  Put cleanup code in Dispose(ByVal disposing As Boolean) above.
        Dispose(True)
        GC.SuppressFinalize(Me)
    End Sub

#End Region

#End Region

End Class
